SX OS Cheat Hacker Guide
========================

--[ 1. Introduction

This small guide attempts to shed some light on finding your own cheat codes
for Switch games using the SX OS Cheat finder as well as detailing the specifics
about the SX OS Cheat Code Format.

--[ 2. Address Space Layout Randomization

The Nintendo Switch Operating System (Horizon OS) implements Address Space 
Layout Randomization (from here on ASLR) for every process. What this means
is that the absolute base address of for example a game's executable or a
game's heap memory are not fixed in stone. SX OS does *not* disable this ASLR 
as it would effectively make your console less secure. The downside of this is 
that you as a cheat hunter will need to keep this in mind when finding cheats, 
but we've tried our best to encapsulate/hide these details at a high level.

When working with pointers in the SX OS Cheat Engine you can have three different
type of pointers:
    * MAIN - memory addresses/pointers relative to the game's NSO executable
    * HEAP - memory addresses/pointers relative to the start of the game's heap
    * BASE - memory addresses/pointers that are neither part of MAIN/HEAP,
             they are displayed a relative to the address space base (usually 0x8000000)

Throughout the SX OS Cheat finder every memory address is thus displayed as:
    [MAIN+xxxx], [HEAP+xxxx], [BASE+xxxx]

When writing actual cheat codes you need to specify what kind of address you are
reading/writing from, we support reading/writing from/to both MAIN and HEAP memory.

Remember that having cheat codes which write to a magic HEAP address are most of
the time not very stable/reliable cheat codes, because the layout of the HEAP is
not always fully deterministic and often times depends on how someone navigates 
through a game. In these cases it is better to study the game logic more and find
pointers (or pointers to pointers, etc.) until you traced back to an address that
resides in MAIN (a pointer in BSS or RO for example). At the end of this guide
you will find a small case study of how the included codes for 
"Mega Man Legacy Collection" work.

--[ 3. SX OS Cheat Code Format

SX OS Cheat Codes are loosely inspired by older cheat engines such as Action Replay.
While old Action Replay cheat codes usually had a fixed width per code, some code
types in the SX OS cheat engine can have a different length. 

Cheat codes are placed inside the sxos folder on your microSD card. In order
for SX OS to pick up your cheat codes they need to be correctly placed in the
right subfolders. This subfolder format works like this:
    /sxos/titles/<titleID>/cheats/<buildID>.txt

Where titleID is the titleID of the game and buildID are the first 8bytes of the
game's build ID formatted as ascii hexadecimals. Both the titleID and buildID for
a running game are displayed below the SXOS logo when you navigate to the cheats
tab in the SX OS Menu. The buildID is needed to properly deal with different
versions of the same game, which might lead to incompatibilities for cheat codes.
When SX OS detects you have cheats on your SD cards for the currently running game
but the buildID mismatches, it offers you to copy over the cheats from the other
buildID to the one of the version you are currently running, if you want to 
experiment with (or fix) the compatibility of certain cheat codes.

A basic cheat code definition will look like this:

[Infinite Health]
11111111 22222222
11111111 22222222
11111111 22222222

Where 'Infinite Health' is the displayed name of the code and the lines containing
'11111111 22222222' are all the codes that belong to this cheat.

The cheat engine supports up to 16 'scratch' registers which can be used for
arbitrary purposes like stashing offsets or memory locations.

There is one special type of code. The "master code" which is not defined by
enclosing the name in '[' and ']' but using '{' and '}' instead. The master code
cannot be disabled and is executed before any other (enabled) cheat code. These
exists to avoid duplication in multiple cheats which share certain characteristics.
An example of master code usage can be seen in the case study for the 
"Mega Man Legacy Collection" cheats you will find further down in this guide.

Below is an overview of the various code types currently implemented in the SX
OS Cheat Engine.

  # Code Type 0: Write to memory

  0TMR00AA AAAAAAAA YYYYYYYY (YYYYYYYY)

  T = width of write (1/2/4/8)
  M = memory type (0 = main nso, 1 = heap)
  R = register to be added as offset
  A = address relative to (M)

  With code type 0 you can do a write to memory.

  # Code Type 1: Conditional statements

  1TMC00AA AAAAAAAA YYYYYYYY (YYYYYYYY)

  T = width of comparison value (1/2/4/8)
  M = memory type (0 = main nso, 1 = heap)
  C = Condition to use for comparison
  A = Address relative to (M)
  Y = Value to compare against

  # Code Type 2: End of conditional statement

  20000000

  This code type terminates an conditional block (Code type 3 or 8)

  # Code Type 3: Looping

  300R0000 VVVVVVVV

  R = Register to use for loop counter
  V = Loop count

  310R0000 

  This code type is used at the end of the loop, use the same R value as
  for the start of the loop.

  # Code Type 4: Load register with value

  400R0000 VVVVVVVV VVVVVVVV

  This code type will load one of the registers with a specific value

  R = Register to be filled
  V = Value to be put in register

  # Code Type 5: Load register with value from memory

  5TMRI0AA AAAAAAAA

  T = Width of value to be loaded from memory (1/2/4/8)
  M = memory type (0 = main nso, 1 = heap)
  R = Load from register index
  I = Load from register flag, set to 1 to load from register R instead of address A
  A = Address relative to (M)

  # Code Type 6: Store value to memory address from register

  6T0RIor0 VVVVVVVV VVVVVVVV

  T = Width of value to be stored to memory
  R = Register index containing the memory address
  I = Increment register flag, set to 1 to increment the register by T after storing
  o = add additional offset from register 'r' 
  r = offset register index
  V = value to be stored to memory

  # Code Type 7: Apply arithmic operation to register

  7T0RC000 VVVVVVVV

  T = Width of value (1/2/4/8)
  R = Register index to apply arithmic operation to
  C = Arithmic operation to apply:
      0 = addition, 1 = subtraction, 2 = multiplication, 3 = shift left, 4 = shift right
  V = Value to be used during arithmic operation

  # Code Type 8: Check for buttons being pressed

  8kkkkkkk

  k = keypad value to check against. the hex values for the various keys are:

    0000001 - A
    0000002 - B
    0000004 - X
    0000008 - Y
    0000010 - Left Stick Pressed
    0000020 - Right Stick Pressed
    0000040 - L
    0000080 - R
    0000100 - ZL
    0000200 - ZR
    0000400 - Plus
    0000800 - Minus
    0001000 - Left
    0002000 - Up
    0004000 - Right
    0008000 - Down
    0010000 - Left Stick Left
    0020000 - Left Stick Up
    0040000 - Left Stick Right
    0080000 - Left Stick Down
    0100000 - Right Stick Left
    0200000 - Right Stick Up
    0400000 - Right Stick Right
    0800000 - Right Stick Down
    1000000 - SL
    2000000 - SR

  Multiple button values can be combined by OR'ing them together. For example
  A+B becomes 0000003, and A+B+X+Y becomes 000000f.

  This code type otherwise behaves the same as the conditional code type 1.

--[ 4. Using the Cheat Finder in SX OS

SX OS Comes with a cheat searcher functionality that will help you in identifying
the memory locations you need in order to write your own cheat codes. You start
by launching a game, when you reach a point in the game where you want to start
searching for cheats you hit the home button, and navigate to the album viewer (SX OS Menu).

You can start a cheat search by navigating to "Cheat Searcher" in the cheat tab of the
SX OS menu. You will be prompted to pick what kind of value you want to start
a cheat search for. If you dont know the answer you can try to approximate it. Lets say
you want to hunt down the memory location of your in-game coins, and you know
that you can accumulate over 1000 coins, you know for sure the data type you are
looking for is gonna be bigger than 8-bit. This takes some experimentation and 
expertise to get used to. 

Once you select the data type a memory dump for the running game will be created 
on your microSD card. This initial memory dump will take a while, it is advised
to use a fast microSD card with enough free space.  If you are looking for a 
specific/exact value, you can now select "Next Search" and pick "Exact Value",
here you can enter the exact value you're looking for (in hexadecimal). Once the
comparison is done it will tell you how many candidate memory locations it found
and whether they are few enough to manually explore.

If there's too many candidates left, you simply exit the SX OS Rom Menu and go
back to the game. Try to grab/lose some coins (or whatever item you're trying 
to cheat) and head back into the SX OS menu's cheat tab, pick "Next Search" and 
specify the condition. This can be "exact value" again if you know the value 
you're looking for, or simply "less than" if you know you just lost some of the 
desired item/stats. Keep iterating the searches until the cheat searcher tells 
you there's few enough candidate memory locations left for you to start 
exploring manually.

Manually exploring memory location candidates can be done by going to "View candidates" 
in the cheats menu. When you select a candidate from the list you will be brought
to the builtin hex editor where you can change the values at these memory locations.
Once you change a value you can go back to the game and see if your change had
any/the desired effect to help in concluding whether you found the right memory 
location.

--[ 5. Case Study of "Mega Man: Legacy Collection" cheat codes.

Currently we only provide a single example of working cheat codes. We would love
to spend all of our time on finding more cheats, but we have different priorities. ;-)

The cheats we found are a slightly interesting example though of the various code
types the SX OS Cheat Engine currently offers. 

Mega Man: Legacy Collection is a collection of old Mega Man games originally 
released for the NES back in the day. The switch "port" of these games is actually
a NES emulator in disguise. The meat of our Mega Man cheat codes hinges on the
"master code" which finds the virtual NES' memory start address, from there we
can apply any RAM patches to the NES memory as we wish. Let's have a look at how
this works.

The full master code looks like this:

-- 8< ------------------------
{Master Code}
580f0000 00d3a2a0
580f1000 038cb840
580f1000 00000008
780f0000 0000000f
-- 8< ------------------------

The usage of '{' and '}' indicates that this is a master code, eg. a code that
cannot be disabled and is always ran at the start of your cheat code list.

Lets break down the master code line by line:
580f0000 00d3a2a0

Code type 5 is 'Load register with value from memory', here we load a 8 byte (64bit)
value, relative from MAIN (0) into register 'f' (15). The offset from the start of
MAIN is 0xd3a2a0. 

In pseudocode this would be something like: 

  register_f = read64(MAIN + 0xd3a2a0)

The next line reads:
580f1000 038cb840                                                               

This one is very similar to the first code, but notice how we have an '1' there.
if you look this up in the SX OS Code Format description above you can see this
is the 'Load from register flag'. If set to '1' we will take the address from the
register specified in the register index field rather than a memory location
relative from MAIN or HEAP. In pseudocode this would be:

  register_f = read64(register_f + 0x38cb840)

The following line '580f1000 00000008' is more of the same, this time reading
the next pointer from offset 8, or in pseudocode:

  register_f = read64(register_f + 0x8)

Then finally we we end with '780f0000 0000000f'. Which uses code type 7 to do
some basic arithmic to the memory location in register f. In pseudo code this
would be:

  register_f = register_f + 15

So in essence all the "master code" does is follow a bunch of pointers and
eventually end up with a pointer in register F that holds the start of the virtual
NES' memory. This register f value can then be used in any cheat codes that need
to write/read from the virtual NES' memory in order to give Mega Man exciting
super powers! ;-)

Let's have a quick look at one of the game specific cheat codes for Mega Man 1:

[MM1 Infinite Health]
400e0000 00000000 0000006a
610f01e0 00000000 0000001c

The first line '400e0000 00000000 0000006a' is using code type #4 to load a 
register with a specific value. In this case we load register E with value 0x6a.
0x6a is the RAM offset for Mega Man's health.

The following line '610f01e0 00000000 0000001c' is using code type #6, which
is "Store value to memory address from register" to write to this location.

Here we say write a 1 byte (8bit) value to the address: register_f + register_e.
The value to be written is 0x1c, the maximum value Mega Man's health can have 
in Mega Man 1.

--[ 6. Closing Words

We hope this guide outlines the possibilities of the cheat engine and the
need for decent master codes a bit. We are looking forward to many community
contributions with new cheat codes and of course suggestions for improving our 
cheat code finder and engine.

 Yours Sincerely,

   Team Xecuter -- Rocking the switch in 2018 and beyond! 
